Artifact for "Faster Coroutine Pipeline" (paper 14)
Michael Spivey

The artifact contains the two implementations of pipelines discussed
in the paper, in addition to the "half-hearted" improvement that
speeds up sequential and not parallel composition, and a Haskell
version of the representation function

    rep :: DirectPipe i o a -> ContPipe i o a

that is the basis for the derivation of ContPipe given in the paper.


GETTING STARTED

The program can be compiled on a Linux system with GHC installed, by
using the command

    ghc -O2 Pipe.hs -main-is Pipe -o pipe

This results in an executable file called 'pipe' that can be used in
the experiments described below.  The code is compatible with GHC
version 8.0.  The command

    ./pipe primes2 10

should result in the first 10 primes being printed to standard output.

ALTERNATIVELY, a Docker image is supplied that contains the object code
for the program and all necessary libraries.  To import the image:

    docker load <pipelines.img.gz

To verify,

    docker run pipelines ./pipe primes2 10

should again print the first 10 primes; use the prefix "docker run pipelines"
in front of any command shown below.


STEP BY STEP

The module contains a main program that expects two arguments on the
command line: one naming an experiment to perform, and the other an
integer saying what size of data to use: this parameter invariably
corresponds to the variable n in Section 5 of the paper.

The following commands are possible, where n = 1000 can be replaced by
any desired parameter:

Print the first 1000 primes
* ./pipe primes0 1000		-- using a sieve based on lazy lists
* ./pipe primes1 1000		-- using DirectPipe
* ./pipe primes2 1000		-- using ContPipe
* ./pipe primes3 1000		-- using HalfPipe
* ./pipe primes4 1000		-- running 'rep primes' as a ContPipe

Order of growth of nested sequential composition (deep_seq)
* ./pipe seq1 1000		-- using DirectPipe
* ./pipe seq2 1000		-- using ContPipe
* ./pipe seq3 1000		-- using HalfPipe

Order of growth of nested parallel composition (deep_par)
* ./pipe par1 1000		-- using DirectPipe
* ./pipe par2 1000		-- using ContPipe
* ./pipe par3 1000		-- using HalfPipe

Interactive line reversal example (parameter ignored)
* ./pipe rev1 0			-- using DirectPipe
* ./pipe rev2 0			-- using ContPipe

DirectPipe and ContPipe are the two implementations of a pipeline
toolkit discussed in the paper, and HalfPipe is an implementation that
improves sequential composition using the ideas of Voigtlaender
referenced in the paper, but leaves parallel composition unimproved.
The command 'primes4' illustrates that 'rep' preserves behaviour,
but is not proposed as a practical implementation of pipelines.

A TCL script 'runme' is provided that regenerates the performance data
presented in the paper.  It runs each example 20 times and outputs the
timing data on standard output in CSV format.

    tclsh runme >results.csv

Alternatively, the Docker image can be used to generate similar figures.

    docker run pipelines tclsh runme >results.csv

The timings used to generate the graphs in the paper are supplied in
the file 'timings.csv'.  The graphs in the printed paper were prepared
using the iWork Numbers spreadsheet, but similar plots in files
'plot1.eps' and 'plot2.eps' can be generated from the CSV data with
the supplied script 'plotme', which depends on gnuplot.

    tclsh plotme results.csv

Note that in the seq<k> and par<k> examples, the parameter n
determines both the depth of nesting and the number of data items
transmitted, so that a linear slowdown due to nesting will result in a
quadratic growth in running time.  In practice, the results appear
close to cubic owing to garbage collector performance, as discussed in
the paper.


MANIFEST

README           -- This file
Makefile         -- Make script to control building
Dockerfile       -- Script for creating Docker image
.dockerignore    -- List of files to exclude from Docker context
pipelines.img.gz -- The Docker image
Pipe.hs          -- Source code from the paper
runme            -- TCL script to conduct timing experiments
plotme           -- TCL script to generate timing plots
timings.csv      -- Timing data as used in the paper
plot1.eps        -- Figure 1 from the paper
plot2.eps        -- Figure 2 from the paper
